<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="fr" lang="fr">
    <head>
        <title></title>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />        
        <link rel="stylesheet" type="text/css" href="../../css/guide.css" />        
        <script type="text/javascript">var basepath = '../../'; var lang = 'fr';</script>        
        <script type="text/javascript" src="../../js/loader.js"></script>        
    </head>
    <body>     
        <h1>Email</h1>
        <p>
           La classe Email permet comme son nom l'indique d'envoyer des e-mails à partir de vos scripts. A savoir cependant : 
        </p>
        <ul>
            <li>Les e-mails sont envoyés au format base64, cela permet une meilleure compatibilité avec les différents caractères linguistiques et clients mail.</li>
            <li>La classe utilise le serveur SMTP configuré dans php.ini, elle ne permet pas encore l'envoi à partir d'un autre serveur.</li>
            <li>Aucune vérification n'est faite sur les adresses mail d'envoi et de réception pour le moment</li>
            <li>Quand c'est possible, le return-path est défini automatiquement avec l'adresse mail de l'expéditeur.</li>
        </ul>
        <blockquote class="warning">
            PHP Oxygen à été développé en UTF-8, les contenus qui seront envoyés par cette classe doivent obligatoirement être encodés au même format.
        </blockquote>

        <h2>Exemple d'utilisation</h2>
        <p>La classe Email est assez simple d'utilisation en voici un exemple :</p>
        <php>
            Email::to('someone@example.com, anotherone@example.com', 'them@example.com')
                    ->from('me@example.com')
                    ->subject('Example mail')
                    ->bodyHtml('&lt;p&gt;Email example&lt;/p&gt;')
                    ->bodyText('Email example')
                    ->addAttachment('file.zip')
                    ->addStringAttachment('My text content', 'attachment.txt')
                    ->send();
        </php>    
        
        <h2>Référence des fonctions</h2>
        
        <h3>to()</h3>
        <p>
            Définit l'adresse ou les adresses des destinataires. Cela peut être une seule adresse, une liste d'adresse 
            séparée par des virgules, point-virgules, espaces ou un tableau contenant les adresses.
        </p>
        <php>
            // Un seul destinataire
            Email::to('someone@example.com');
            
            // Plusieurs destinataires séparés par des virgules
            Email::to('someone@example.com, anotherone@example.com');
            
            // Un tableau de destinataires
            Email::to(array('someone@example.com', 'anotherone@example.com'));
            
            // Le mix des différentes règles fonctionne aussi
            Email::to('someone@example.com', 'someone@example.com, anotherone@example.com', array('someone@example.com', 'anotherone@example.com'));
        </php>
        <blockquote class="info">
            La fonction va automatiquement ajouter qu'une seule fois la même adresse afin d'éviter 
            plusieurs envois à un même destinataire.
        </blockquote>
        
        <h3>from()</h3>
        <p>Définit l'adresse et optionnellement le nom de l'expéditeur du mail.</p>
        <php>
            // Sans le nom
            Email::to('someone@example.com')->from('me@example.com');
            
            // Avec le nom
            Email::to('someone@example.com')->from('me@example.com', 'John Bob');
        </php>                
        
        <h3>subject()</h3>
        <p>Définit le sujet du mail.</p>
        
        <h3>bodyText()</h3>
        <p>Définit le contenu du mail au format texte brut.</p>
        
        <h3>bodyHtml()</h3>
        <p>Définit le contenu du mail au format html.</p>
        <blockquote class="info">           
            Si vous définissez un contenu en HTML il est préférable de définir également un contenu textuel. 
            Certains moteurs anti-spams peuvent filtrer les messages ne contenant pas les deux.<br />
            Il est également préférable de bien définir votre contenu html en l'englobant dans &lt;html /&gt;&lt;body /&gt;
        </blockquote>
        
        <h3>priority()</h3>
        <p>
            Permet de définir la priorité du l'e-mail. Doit être un entier entre 1 (le plus haut niveau) et 5 (le plus bas)
        </p>
        
        <h3>cc()</h3>
        <p>
            Permet d'ajouter des destinataires en copie carbone. Cela peut être une seule adresse, une liste d'adresse 
            séparée par des virgules ou un tableau d'adresses.
        </p>
        
        <h3>bcc()</h3>
        <p>
            Permet d'ajouter des destinataires en copie carbone cachée. Cela peut être une seule adresse, une liste 
            d'adresse séparée par des virgules ou un tableau d'adresses.
        </p>
        
        <h3>cci()</h3>
        <p>Alias de bcc().</p>
        
        <h3>addAttachment()</h3>
        <p>
            Permet d'ajouter un fichier joint. Le premier paramètre doit être un fichier présent sur le serveur. 
            Pour plusieurs fichiers vous devez définir la fonction plusieurs fois
        </p>
        <php>
            $email = Email::to('someone@example.com')->from('me@example.com')->subject('test');
            
            // Ajout simple
            $email->addAttachment(WWW_DIR.'images/01.jpg');
            
            // Ajout avec renommage du fichier joint
            $email->addAttachment(WWW_DIR.'images/01.jpg', 'image.jpg');
            
            // Ajout avec renommage du fichier et définition forcée du mimetype
            $email->addAttachment(WWW_DIR.'images/01.jpg', 'image.jpg', 'image/jpeg');
        </php>
        <blockquote class="warning">
            Si il n'est pas défini, le mimetype est détecté par l'extension du fichier à joindre et non par l'extension 
            du renommage.
        </blockquote>
        
        <h3>addStringAttachment()</h3>
        <p>
            Permet d'ajouter une chaine de caractères comme un fichier joint (par exemple avec une génération de PDF à 
            joindre par mail). Pour plusieurs fichiers vous devez définir la fonction plusieurs fois.
        </p>
        <php>
            $email = Email::to('someone@example.com')->from('me@example.com')->subject('test');
            
            // Ajout simple
            $email->addStringAttachment('Contenu de mon fichier', 'monfichier.txt');
            
            // Ajout avec définition forcée du mimetype
            $email->addStringAttachment('valeur1;valeur2;valeur3', 'monfichier.txt', 'text/csv');
        </php>
        <blockquote class="warning">
            Contrairement à addAttachment() la détection du mimetype se fait sur l'extension du nom de fichier à joindre.
        </blockquote>
        
        <h3>send()</h3>
        <p>
            Envoi le mail. Retourne true en cas de succès. Vous pouvez définir le seul paramètre à false si vous ne 
            désirez pas utiliser le return-path du serveur (true par défaut).
        </p>
    </body>            
</html>